---
title: "Workflow - Transition Rules"
space: "Frappe Framework"
url: "https://support.aakvatech.com/Frappe Framework/workflow-transition-rules"
updated: "2026-07-22"
---

### 🔁 Transition Rules – What, Why & How

**Transition Rules** define how a document moves from one **Workflow State** to another. Each rule specifies the *current state*, the *next state*, the *role allowed to transition*, the *action label*, and optionally, a *condition*.

These rules control both the **flow logic** and **access permissions**. They are essential for:
- Preventing unauthorized actions
- Enforcing sequential approvals
- Automating field updates
- Enabling conditional transitions (e.g., only allow approval if total amount < 100,000)

---

### 🧱 Fields in Transition Rules

| Field | Purpose |
|-------|---------|
| **State** | Current state of the document |
| **Action** | Label/button that appears in the UI (e.g., “Approve”, “Reject”) |
| **Next State** | The state the document moves to on action |
| **Allowed Role** | Role permitted to perform the action |
| **Condition (Optional)** | Python expression to control when this transition is allowed |
| **Allow Self Approval** | Let the document owner approve their own documents (default: false) |

---

### 📜 How to Write Conditions

The `condition` field allows you to use Python-like expressions to control when a transition is allowed.

**Syntax:**
```python
doc.branch == frappe.session.user_branch
```

**Examples:**

1. Only approve if document total is less than 50,000:
   ```python
   doc.total < 50000
   ```

2. Only proceed if branch matches the current user’s branch:
   ```python
   doc.branch == frappe.db.get_value("Employee", frappe.session.user, "branch")
   ```

3. Only allow transition if the document has attachments:
   ```python
   len(doc.attachments) > 0
   ```

> The `doc` object is the current document. You can also access `frappe.db`, `frappe.session`, and time utilities like `frappe.utils.now()`.

---

### 👤 Restricting Workflow by Branch (Use Case: Branch Manager)

To restrict branch managers so they **only see and approve documents from their own branch**, do the following:

#### 1. **Add a branch field** to your target DocType (e.g., Sales Invoice, Leave Application).

#### 2. **Assign branch field** to each user (via Employee or User DocType).

#### 3. **Use a condition** in the workflow transition:

```python
doc.branch == frappe.db.get_value("Employee", frappe.session.user, "branch")
```

This ensures that only documents from the user’s own branch are eligible for transition.

#### 4. **Set role-based permissions** in:
- Role Permission Manager
- Workflow Transition “Allowed Role” field

#### 5. **Email Notification Restriction:**
Emails are only sent to users with access to act on a transition. Therefore, with the condition above in place, **only branch-specific managers** will be notified.

---

### ✅ Why This Matters

Without transition rules:
- Any user with the right role might access or approve any document.
- Data segregation (e.g., by branch, region) is impossible.
- It’s hard to enforce granular security and compliance rules.

Using conditions with transitions helps to enforce **data privacy**, **process hierarchy**, and **regional autonomy**—all critical for growing businesses.